home *** CD-ROM | disk | FTP | other *** search
/ Aminet 1 (Walnut Creek) / Aminet - June 1993 [Walnut Creek].iso / usenet / sources / volume90 / unix / ls_3_1 / part01 / ls.doc next >
Text File  |  1990-04-10  |  8KB  |  266 lines
  1.                    LS 3.0 USER DOCUMENTATION
  2.  
  3. -----------------------------------------------------------------------
  4.  
  5.      LS 3.0 - A versatile Amiga directory listing utility.
  6.  
  7. Revision History:
  8.  
  9.   V1.0    August 1986 Written from scratch by Justin V. McCormick.
  10.   V2.0  November 1988 Revised for Lattice 5.0 and made 1.3 compatible.
  11.   V2.1  December 1988 Minor size reduction, fixed a few bugs from 2.0.
  12.   V2.2  December 1988 Fixed status return and multiple wildcard pathnames.
  13.   V3.0  July 25, 1989 Instant sorting, best-fit output, new features.
  14.   V3.1  July 29, 1989 Bug fixes, new output width and height options.
  15.  
  16. Notices:
  17.  
  18.   This program is placed in the public domain with the
  19. understanding that the author makes no claims or guarantees with
  20. regard to its suitability for any given application, and that
  21. the author assumes no responsibility for damages incurred by its
  22. usage.  Any resemblance of this program to any other program,
  23. either living or dead, is purely coincidental.
  24.  
  25.   Feel free to borrow this code and make millions of dollars
  26. from its sale or commercial use, but please give credit where
  27. credit is due.
  28.  
  29.   Please do not send me money or stolen software!  I enjoy mail,
  30. phone calls, and legitimate software contributions of all kinds.
  31.  
  32.            Thanks for your encouragement and support,
  33.                       Justin V. McCormick
  34.  
  35. I can be reached via:
  36.  
  37.   BIX: jmccormick
  38. PLINK: JVM
  39.  
  40. PHONE: 303-290-8429
  41.  
  42. USMAIL: 8330 E. Quincy Ave.
  43.         Bldg. C, #312
  44.         Denver CO, 80237
  45.  
  46.  
  47.  
  48. Synopsis:
  49. ---------
  50.  
  51.   Features intelligent columnar listing, versatile sort options,
  52. UNIX-style pattern matching, recursive subdirectory listing,
  53. customized output formatting and much more!
  54.  
  55. Usage:
  56.         LS [options] [pattern1] [pattern2] ...
  57.  
  58.  
  59. Installation:
  60. -------------
  61. LS can be put in your C: directory where LIST and DIR are
  62. normally found.  LS can be made resident in your
  63. startup-sequence, but you must set the pure bit on LS after
  64. dearchiving to prevent spurious warnings:
  65.  
  66.     PROTECT C:LS +P
  67.  
  68. Or you can ignore the pure bit warning in the startup-sequence:
  69.  
  70.     RESIDENT >NIL: C:LS PURE
  71.  
  72.  
  73. The Command Line:
  74. -----------------
  75.  
  76.   All arguments are optional.  The default action is to give a
  77. short columnar listing, sorted alphabetically, using the current
  78. directory.  Alphabetizing is always case insensitive.
  79.  
  80. You can group your options together in any order, like this:
  81.  
  82.     LS -tlr df0:
  83.  
  84. Or you can have options specified independently:
  85.  
  86.     LS -t -l -r df0:
  87.  
  88. However, if you specify several file or path names, the options
  89. will return to their default settings between paths.  Thus, you
  90. have a command like this:
  91.  
  92.     LS -l df0: -r df0:
  93.  
  94. This would give you a two listings of df0:, the first one a long
  95. listing, and the second one a reverse sorted short listing.
  96.  
  97.  
  98. Options:
  99. --------
  100.  
  101.   There are many command options for LS.  You can get a quick
  102. reference list of options by typing:
  103.  
  104.     LS -?
  105.  
  106. Here is the complete list and description of the options:
  107.  
  108. c   Show filenotes, implies long listing.
  109. d   Show directory entries only.
  110. f   Show file entries only.
  111. h   Same as ?, help!
  112. k   Do not use ANSI escape codes in output (for colored text).
  113. l   Give long listing.
  114. n   Do not sort entries before displaying.
  115. p   Permit system requests ("Please insert disk xxx in any drive...").
  116. r   Reverse sort direction.
  117. s   Sort entries by size.
  118. t   Sort entries by date.
  119. v <pattern> 
  120.   Do not show entries that match the given pattern.
  121.  
  122. D   Show directory entries last.
  123. H   Do not print directory headings or subtotals.
  124. I   Non-interactive short listings, no "MORE" prompt between pages.
  125. M   Mix directory and file entries together in final output list.
  126. P   Print full pathnames for all entries, implies long listing.
  127. R   Recursive listing, descend into subdirectories that matches pattern.
  128. T   Print grand total of all entries.
  129.  
  130.   If LS cannot read the current CLI window size, LS assumes the
  131. output is 77 columns by 23 rows.  The following two options let
  132. you control the output page width and length of the short
  133. columnar listing:
  134.  
  135. X <wide>
  136.   Set short listing page width to the given number of columns.
  137. Y <high>
  138.   Set short listing page length to the given number of rows.
  139.  
  140.   There are two special options that expect a valid directory or
  141. filename after the option:
  142.  
  143. N <name>
  144.   Show entries that are newer (more recent than) the given entry name.
  145. O <name>
  146.   Show entries that are older (less recent than) the given entry name.
  147.  
  148.   By using these two options, you can generate a list of files
  149. newer or older than a given file or directory.  For instance,
  150. suppose you had a directory containing C source files for a
  151. project.  Typing "LS -t df0:" produces the following list of
  152. files sorted by time:
  153.  
  154.     joe.c  fred.c  pete.c  ted.c  sam.c
  155.  
  156. Now, if we give the following command:
  157.  
  158.     LS -N df0:pete.c df0:
  159.  
  160. The following files newer than pete.c would be listed:
  161.  
  162.     ted.c  sam.s
  163.  
  164. Also, -N and -O can be used together.  This command:
  165.  
  166.     LS -N df0:fred.c -O df0:ted.c df0:
  167.  
  168. would produce the only file newer than fred.c and older than ted.c:
  169.  
  170.     pete.c
  171.  
  172. Tip:  If you need to list files older or newer than a certain
  173. date, rather than a certain file, you can do this:
  174.  
  175.   echo >RAM:datemark "Marker"    ; Create a temp file in RAM:
  176.   setdate RAM:datemark 07-Jul-89 ; Set the datestamp for the temp file
  177.   LS -N ram:datemark df0:        ; List files newer than "datemark"
  178.   delete ram:datemark            ; Remove the temp file
  179.  
  180.  
  181. Formatted Output:
  182. -----------------
  183.  
  184.   For customized output, there is a special option that expects
  185. a format rule as the next "option":
  186.  
  187. F <format>
  188.   Format output with <format), with the following special symbols:
  189.  
  190.     %p   Print the protection bits
  191.     %d   Print the date, YY-MM-DD
  192.     %t   Print the time, hh-mm-ss
  193.     %b   Print the number of filesystem blocks used by this entry.
  194.     %s   Print the number of bytes used by this entry.
  195.     %n   Print the name of the entry.
  196.     %%   Print a percent symbol.
  197.     \n   Print a linefeed.
  198.     \t   Print a tab.
  199.     \\   Print a backslash symbol.
  200.  
  201. The default format rule that LS uses for long listings looks like this:
  202.  
  203.     -F "%p %d %t %4b %8s %n\n"
  204.  
  205.   Any of the format options that begin with the '%' symbol can
  206. have an optional pad count that lets you specify how many
  207. columns to use.  For example:
  208.  
  209.     -F "%40n\n"
  210.  
  211. would print each entry name right justified in a field of 40 columns.
  212.  
  213.   You can use this feature of LS to help create simple batch
  214. command files.  For example, look at this command:
  215.  
  216.     LS -PF "copy %n RAM:\n" df0:*.h
  217.  
  218.   This tells LS to perform a listing using full pathnames with a
  219. special format, matching only filenames that end with ".h" in
  220. directory df0:.  Suppose df0:  has the following files in it:
  221.  
  222.     joe.h  fred.h  pete.h  ted.h
  223.  
  224. Our example LS command would result in the following list of commands:
  225.  
  226.     copy df0:fred.h RAM:
  227.     copy df0:joe.h RAM:
  228.     copy df0:pete.h RAM:
  229.     copy df0:ted.h RAM:
  230.  
  231. We could create a script file from this by redirecting the
  232. output of LS to a temporary file:
  233.  
  234.     LS >ram:templist -PF "copy %n RAM:\n" df0:*.h
  235.     EXECUTE ram:templist    ;Do the script
  236.     DELETE ram:templist     ;Delete it
  237.  
  238.  
  239. Wildcards:
  240. ----------
  241.  
  242.   Wildcards may be used in file names and in the last level of a
  243. directory path name.  The UNIX-style '*' character is used to
  244. match any number of characters, and a '?' matchs any single
  245. character.  If you need to specify a pathname with spaces in it
  246. like "Wombat Soup", you need to put quotes around it.  LS can
  247. process up to 30 separate pathname patterns in per command line.
  248.  
  249. Here are some simple examples:
  250.  
  251.     LS df0:*.info      ; List all .info files in df0:
  252.     LS df0:*/*.info    ; List all dirs and .info files in df0:
  253.     LS df0:L*/*.info   ; List dirs that start with 'L' and .info files
  254.  
  255.   Also, wildcards are helpful when you are trying to avoid showing
  256. certain files with the "-v <pattern>" option.  For instance:
  257.  
  258.     LS -v *.info        ; List current dir, do not show .info files.
  259.     LS -v *.info df0:   ; Same as above but lists df0: instead.
  260.     LS -v *.info df0:C* ; List entries that start with the letter "c"
  261.                         ; in df0:, but do not list .info files.
  262.  
  263. ---------------------------------------------------------------------
  264.         May all your directory listings be more readable,
  265.                       Justin V. McCormick
  266.